home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / BASIC / LIB / EVENTSHELL / DOCS / Menus < prev    next >
Text File  |  1996-05-18  |  15KB  |  604 lines
  1.  
  2. PROCshell_AttachMenu()
  3. =>    int    window handle
  4.     int    icon handle
  5.     int    item handle
  6.     bool    shift flag (not implemented)
  7.     bool    ctrl flag (not implemented)
  8.     bool    alt flag (not implemented)
  9.  
  10. The shift, ctrl and alt flags are for future
  11. enhancements to the library and should be set
  12. to 0 on this release.
  13.  
  14. If the menu is attached to an icon (rather than
  15. a window work area) a click with SELECT or MENU
  16. will open the menu. Also the button type of the
  17. icon is changed to 3 (click) to ensure the menu
  18. pops up when SELECT is used.
  19.  
  20. User FN (PROCshell_AttachMenu)
  21. =>    str    text of menu selection
  22.  
  23. The function to call when the user makes
  24. a choice from the menu.
  25.  
  26. --------------------------------------------------------
  27.  
  28. PROCshell_AttachMenuMaker()
  29. =>    int    window handle
  30.     int    icon handle
  31.     str    function name
  32.  
  33. Registers a function to be called before the
  34. menu is opened, allowing ticking, shading etc
  35. of menu items.
  36.  
  37. User FN (PROCshell_AttachMenuMaker)
  38. =>    int    window handle over which MENU
  39.          was pressed
  40.     int    icon handle over which MENU was
  41.          pressed (-1 for no icon)
  42.  
  43. This function is called before the menu is
  44. opened.
  45.  
  46. --------------------------------------------------------
  47.  
  48. PROCshell_AttachFontMenu()
  49. =>    int    item handle
  50.     str    function to call when menu_select
  51.          event occurs (optional, may be "")
  52.  
  53. Use this routine to attach the FontMenu to an icon or
  54. a window. Attach the FontMenu to an existing menu
  55. structure with PROCshell_AttachFontSubMenu.
  56.  
  57. This routine will attempt to load the necessary
  58. 'FontMenu' support module if it is not already
  59. loaded. It expects to find it in the
  60. EvntShell$Path (usually inside !EvntShell).
  61.  
  62. User FN (PROCshell_AttachFontMenu) 
  63. =>    str    selection string
  64.  
  65. <=    int    ignored
  66.  
  67. This function can be used to discover the name
  68. of the font (if any) that has been selected in
  69. the FontMenu. Use FNshell_FontMenuGetLastSelectedFont
  70. for this.
  71.  
  72. --------------------------------------------------------
  73.  
  74. FNshell_FontMenuGetLastSelectedFont
  75. =>    None
  76.  
  77. <=    str    font name (could be "")
  78.  
  79. This routine should be used in the function
  80. called when a menu_select event has occurred to
  81. discover if font menu selection has been made,
  82. and if so the name of the font.
  83.  
  84. If no valid font menu selection has been made
  85. the function will return "" and no action should
  86. be taken.
  87.  
  88. --------------------------------------------------------
  89.  
  90. PROCshell_FontMenuSelectFont()
  91. =>    str    name of font to select
  92.  
  93. The font name is used by the library routines
  94. to decide which font name to select when the
  95. font menu opens. As the same font menu can be
  96. used by different applications it is important
  97. to set this up just before the menu opens.
  98.  
  99. --------------------------------------------------------
  100.  
  101. PROCshell_AttachMenuDBox()
  102. =>    int    menu item handle
  103.     str    window identifier
  104.     str    function name
  105.     str    function name
  106.  
  107. Calling this routine will automatically setup the sub
  108. menu arrow on the menu item, and also set the 'menu
  109. warning' flag. It is not necessary to do this in the
  110. menu editor.
  111.  
  112. User FN (PROCshell_AttachMenuDBox)
  113. =>    int    window handle
  114.  
  115. The function to call after creating the window
  116. but before opening it. This can be used to fill
  117. in icon fields etc. A function name of "" may
  118. be used if you don't need to call a function.
  119.  
  120. User FN (PROCshell_AttachMenuDBox)
  121. =>int    window handle
  122.  
  123. The function to call after opening the window.
  124. A function name of "" may be used if you don't
  125. need to call a function.
  126.  
  127. --------------------------------------------------------
  128.  
  129. PROCshell_OpenMenu()
  130. =>    int    menu x coordinate
  131.     int    menu y coordinate
  132.     int    handle of menu to open
  133.  
  134. Normally this routine is called internally
  135. by the library routines in response to menu
  136. open events set up by PROCshell_AttachMenu.
  137. In some circumstances it may be advantageous
  138. to call it from the user applications.
  139.  
  140. Note that this routine checks the last window/
  141. icon pair clicked over and assumes that the
  142. menu is attached to these. If you open the
  143. menu in response to a click on the iconbar
  144. icon the Y coordinate will be ignored. In
  145. general you should always attach menus to
  146. windows or window/icon pairs rather than using
  147. this call.
  148.  
  149. --------------------------------------------------------
  150.  
  151. FNshell_MenuLastXPos
  152. Returns the X coordinate of the last menu
  153. opened by PROCshell_OpenMenu.
  154.  
  155. --------------------------------------------------------
  156.  
  157. FNshell_MenuLastYPos
  158. Returns the Y coordinate of the last menu
  159. opened by PROCshell_OpenMenu.
  160.  
  161. --------------------------------------------------------
  162.  
  163. PROCshell_MenuShade()
  164. =>    int    menu or item handle
  165.     int    state
  166.  
  167. Shades menu items. If a menu handle is
  168. given then all items in the menu are
  169. shaded or deshaded.
  170.  
  171. Menu Shade States
  172. The state is 0 for no shading, non 0 for shading.
  173.  
  174. --------------------------------------------------------
  175.  
  176. PROCshell_MenuShadeAllItems()
  177. =>    int    menu handle
  178.  
  179. Shades all the menu items in the specified menu
  180.  
  181. --------------------------------------------------------
  182.  
  183. PROCshell_MenuUnshadeAllItems()
  184. =>    int    menu handle
  185.  
  186. Unshades all the menu items in the specified menu
  187.  
  188. --------------------------------------------------------
  189.  
  190. PROCshell_MenuTick()
  191. =>    int    menu or item handle
  192.     int    state
  193.  
  194. Adds or removes ticks for menu
  195. items. If a menu handle is given
  196. then all items in the menu are
  197. ticked or not ticked.
  198.  
  199. See also PROCshell_MenuTickOnly1,
  200.          PROCshell_MenuTickOnly2
  201.  
  202. Menu Tick States
  203. The state is 0 for no  tick, non 0 for a tick.
  204.  
  205. --------------------------------------------------------
  206.  
  207. PROCshell_MenuTickAllItems()
  208. =>    int    menu handle
  209.  
  210. Adds ticks to every item in the specified menu
  211.  
  212. See also    PROCshell_MenuTickOnly1,
  213.             PROCshell_MenuTickOnly2
  214.             PROCshell_MenuUntickAllItems
  215.          
  216. --------------------------------------------------------
  217.  
  218. PROCshell_MenuUntickAllItems()
  219. =>    int    menu handle
  220.  
  221. Removes ticks from every item in the specified menu
  222.  
  223. See also    PROCshell_MenuTickOnly1,
  224.             PROCshell_MenuTickOnly2
  225.             PROCshell_MenuTickAllItems
  226.          
  227. --------------------------------------------------------
  228.  
  229. PROCshell_MenuPutData()
  230. =>    int    menu item handle or menu handle
  231.     str    data to write into menu item
  232.  
  233. This routine is used to alter the items of a
  234. menu when the program runs. The width of the
  235. menu is adjusted automatically.
  236.  
  237. If a menu handle is passed to this routine the
  238. title is changed, but it is clearer to use the
  239. call to PROCshell_MenuPutTitle.
  240.  
  241. --------------------------------------------------------
  242.  
  243. PROCshell_MenuPutTitle()
  244. =>    int    menu handle
  245.     str    title
  246.  
  247. The menu title is truncated to 12 characters, but no
  248. error occurs.
  249.  
  250. --------------------------------------------------------
  251.  
  252. PROCshell_AttachSubMenu()
  253. =>    int    item handle
  254.     int    submenu menu handle
  255.     str    function to call when menu_warning
  256.          message is received (optional, may
  257.          be "")
  258.  
  259. User FN (PROCshell_AttachSubMenu) 
  260. =>    int    window handle
  261.     int    icon handle
  262.  
  263. <=    int    junk
  264.          
  265. --------------------------------------------------------
  266.  
  267. PROCshell_AttachFontSubMenu()
  268. =>    int    item handle
  269.     str    function to call when menu_warning
  270.          message is received (optional, may
  271.          be "")
  272.  
  273. This routine will attempt to load the necessary
  274. 'FontMenu' support module if it is not already
  275. loaded. It expects to find it in the
  276. EvntShellSystem$Path (usually in !EvntShell).
  277.  
  278. User FN (PROCshell_AttachFontSubMenu) 
  279. =>    int    window handle
  280.     int    icon handle
  281.  
  282. <=    int    junk
  283.  
  284. This function can be used to set the currently
  285. selected font in the menu about to be opened.
  286. Use PROCshell_FontMenuSelectFont to do this.
  287.  
  288. --------------------------------------------------------
  289.  
  290. PROCshell_MenuWritable()
  291. =>    int    menu or menu item handle
  292.     int    state
  293.     int    size of indirected buffer
  294.     str    validation string
  295.  
  296. Makes the given menu item writable or non writable
  297. depending on the state parameter. If a menu handle
  298. is given then all items in the menu are made
  299. writable or non writable.
  300.  
  301. MenuWritable States
  302. The state is 0 for non writable, non 0
  303. for writable.
  304.  
  305. --------------------------------------------------------
  306.  
  307. PROCshell_MenuDotted()
  308. =>    int    menu or menu item handle
  309.     int    state
  310.  
  311. Adds or removes a dotted line from below
  312. the given menu item. If a menu handle is
  313. given instead all items in the menu are
  314. effected.
  315.  
  316. MenuDotted States
  317. The state is 0 for non writable, non 0
  318. for writable.
  319.  
  320. --------------------------------------------------------
  321.  
  322. FNshell_MenuNew()
  323. =>    str    menu title (11 characters max)
  324.     str    menu identifier (for
  325.          future use)
  326.     int    nr of items in this menu
  327.          (approximate only, needed
  328.          to overcome a MenuUtils bug)
  329.  
  330. <=    int    menu handle
  331.          
  332. Creates a new menu with the given title.
  333.  
  334. --------------------------------------------------------
  335.  
  336. FNshell_MenuAdd()
  337. =>    int    menu or menu item handle
  338.     str    text for menu item
  339.     str    fn to call when item is selected
  340.  
  341. <=    int    menu item handle
  342.          
  343. Adds a new item to an existing menu. If a menu
  344. handle is given then the new item is added to
  345. the end of the menu, if an item handle is given
  346. the new item is added before the existing item.
  347.  
  348. User FN (FNshell_MenuAdd)
  349. =>    int    menu decode block
  350.  
  351. Menu decode block
  352. blk+00 position of selected menu item in menu
  353.        (starting from 0)
  354. blk+04 pointer to selected item data
  355. blk+08 selected item handle or zero if item
  356.        was created without MenuUtils
  357. blk+12 pointer to text string of selected item
  358. blk+16 position of parent menu item in menu
  359.        (starting from 0)
  360. blk+20 pointer to parent item data
  361. blk+24 parent item handle or zero if item was
  362.        created without MenuUtils
  363. blk+28 pointer to text string of parent item 
  364.  
  365. --------------------------------------------------------
  366.  
  367. PROCshell_MenuTickOnly1()
  368. =>    int    menu handle
  369.     int    position of item in menu
  370.  
  371. Ticks only the item given by the menu handle
  372. and the position of the item. This call is
  373. provided for when you don't know the handle
  374. of the menu item.
  375.  
  376. See also PROCshell_MenuTickOnly2
  377.  
  378. --------------------------------------------------------
  379.  
  380. PROCshell_MenuTickOnly2()
  381. =>    int    menu item handle
  382.  
  383. Ticks only the item given by the menu item
  384. handle.
  385.  
  386. See also PROCshell_MenuTickOnly1
  387.  
  388. --------------------------------------------------------
  389.  
  390. PROCshell_MenuColours()
  391. =>    int    menu item handle
  392.     int    foreground colour    (0-15)
  393.     int    background colour    (0-15)
  394.  
  395. Sets the foreground and background colours
  396. of the item given. Note that the default
  397. colours are set out in the Style Guide.
  398.  
  399. --------------------------------------------------------
  400.  
  401. FNshell_MenuMakeFromFile()
  402. =>    str    menu title
  403.     str    menu identifier (for future use)
  404.     str    menu selection function
  405.     str    full file name of command
  406.          file
  407.  
  408. <=    int    menu handle
  409.          
  410. Creates a new menu with the given title,
  411. taking the menu items from the specified
  412. menu command file.
  413.  
  414. The command file consists of menu text items,
  415. blank lines and lines starting with a '#'
  416. character are ignored.
  417.  
  418. Example Command File..
  419.  
  420. Adachi
  421. Fuji HQ
  422. Panasonic HQ
  423. Sony
  424.  
  425. --------------------------------------------------------
  426.  
  427. PROCshell_MenuSortItems()
  428. =>    int    menu handle
  429.     str    comparision function (optional,
  430.          may be "")
  431.     bool    ascending flag, non 0 for
  432.          ascending sort, 0 for
  433.          descending sort
  434.     int    first item number to sort
  435.          (normally 0)
  436.     int    last item number to sort
  437.  
  438. This routine is used to sort the menu items
  439. into order. It should not be used if the items
  440. do not have the same handler routine, as only
  441. the menu text is moved around.
  442.  
  443. If a last item number is given that exceeds
  444. the number of items in the menu it is reset
  445. to be equal to the number of items.
  446.  
  447. If the comparision function is "" then a default
  448. one is used which retrieves the menu items as
  449. strings and compares them.
  450.  
  451. Comparision FN (PROCshell_MenuSortItems)
  452. =>    int    first  element nr
  453.     int    second element nr
  454.  
  455. <=    bool    TRUE if value of first element
  456.          is less than the second,
  457.          otherwise FALSE
  458.  
  459. --------------------------------------------------------
  460.  
  461. PROCshell_AttachColourPopupMenu()
  462. =>    int    window handle
  463.     int    menu    icon handle
  464.     int    display icon handle
  465.     int    menu handle
  466.     str    user function (optional)
  467.     str    preopen function (optional)
  468.  
  469. Provides for automatic updating of a display
  470. icon when a selection is made from the
  471. attached colour menu. If a user function name
  472. is not supplied then the display icon shows
  473. the selected menu item background colour.
  474.  
  475. The button type of the menu icon is changed
  476. to 3 to ensure the menu opens when <SELECT>
  477. is used.
  478.  
  479. User FN (AttachColourPopupMenu)
  480. =>    int    window handle
  481.     int    display icon handle
  482.     str    menu text of selected item
  483.  
  484. <=    bool    TRUE if display icon should be
  485.          automatically updated, FALSE
  486.          otherwise
  487.  
  488. Preopen FN (AttachColourPopupMenu)
  489. =>    int    menu handle
  490.  
  491. --------------------------------------------------------
  492.  
  493. PROCshell_AttachPopupMenu()
  494. =>        window handle
  495.     int    menu icon handle
  496.     int    display icon handle (optional,
  497.            may be -1)
  498.     int    menu handle
  499.     str    user function (optional, may be "")
  500.  
  501. Provides for automatic updating of a display
  502. icon when a selection is made from the
  503. attached menu  if a user function name is
  504. not supplied.
  505.  
  506. The button type of the menu icon is changed
  507. to 3 to ensure the menu opens when <SELECT>
  508. is used.
  509.  
  510. User FN (AttachPopupMenu)
  511. =>    int    window handle
  512.     int    display icon handle
  513.     str    menu text of selected item
  514.  
  515. <=    bool    TRUE if text should be inserted
  516.          in the display icon, FALSE
  517.          otherwise
  518.  
  519. --------------------------------------------------------
  520.  
  521. PROCshell_MenuDelete()
  522. =>int    menu or menu item handle
  523.  
  524. Deletes a menu item or a whole menu if
  525. a menu handle is specified. Note that if
  526. a menu is deleted any menu events are also
  527. deleted - so if you are deleting and then
  528. re-creating a menu you must also attach
  529. the new menu again.
  530.  
  531. --------------------------------------------------------
  532.  
  533. FNshell_MenuGetItemHandle()
  534. =>    int    menu handle
  535.     int    address of menu selection block
  536.  
  537. <=    int    item handle
  538.  
  539. Returns 0 if item cannot be found, or if item belongs
  540. to a menu that was not created with the MenuUtils module
  541.  
  542. It should normally not be necessary to use
  543. this call as the item handle is returned
  544. when the menu item is created (so store it
  545. if you are likely to need it later!)
  546.  
  547. Menu Selection Block
  548. the block contains :
  549.    0    Item in main menu selected.
  550.    4    Item in 1st submenu.
  551.    8    Item in 2nd submenu.
  552.   ++    ++
  553.     Terminated by -1
  554.  
  555. A selection block is normally returned by
  556. the wimp when a menu selection has been
  557. made.
  558.  
  559. --------------------------------------------------------
  560.  
  561. FNshell_MenuGetItemHandler()
  562. =>    int    menu handle
  563.     int    item number
  564.  
  565. <=    str    item handler FN
  566.  
  567. --------------------------------------------------------
  568.  
  569. FNshell_MenuGetItemHeight()
  570. =>    int    menu handle
  571.  
  572. <=    int    item height (os units)
  573.          
  574. --------------------------------------------------------
  575.  
  576. FNshell_MenuCalculateHeight()
  577. =>    int    menu handle
  578.  
  579. <=    int    height of menu (OS units)
  580.  
  581. --------------------------------------------------------
  582.  
  583. FNshell_MenuGetItemText()
  584. =>    int    menu handle
  585. int    item handle
  586.  
  587. <=    str    text of menu item
  588.  
  589. --------------------------------------------------------
  590.  
  591. FNshell_MenuGetNrDotted()
  592. =>    int    menu handle
  593.  
  594. <=    int    nr of items that have a dotted line
  595.          under them
  596.  
  597. --------------------------------------------------------
  598.  
  599. FNshell_MenuGetNrItems()
  600. =>    int    menu handle
  601.  
  602. <=    int    nr of items in menu
  603.  
  604. --------------------------------------------------------